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About This Manual 


Objectives of This Manual 

This manual provides user and reference information for the Paris interface to the Version 2.0 release 
of the Image File Interface. Separate manuals are available for the C* and CM Fortran interfaces. 


Intended Audience 

This manual is intended for programmers using the Image File Interface. The reader is assumed to 
be familiar with basic Paris programming. 


Revision Information 

This is the first release of this manual. 


Organization of This Manual 

Chapter 1 The Image File Interface 

Provides a brief introduction to Image File Interface, including an overview of the 
routines and information on how to use them. 

Chapter 2 The Image File Interface Routines 

Provides separate detailed descriptions of each routine. 


Related Documents 

This manual is one of three that make up the Connection Machine Visualization Programming 
documentation set. The other two are: 

■ Generic Display Interface Reference Manual for Paris 

■ *Render Reference Manual for Paris 
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Notation Conventions 

The table below displays the notation conventions observed in this manual. 

Convention Meaning 


bold typewriter C/Paris and Fortran/Paris language elements, such as operators, key¬ 
words, and function names, when they appear embedded in text or in 
syntax lines. Also UNIX and CM System Software commands, com¬ 
mand options, and file names. 

italics Argument or parameter names and placeholders, when they appear em¬ 

bedded in text or syntax lines. 

ANY^FE_ARRAY Signals that the array may be any data type on the front end. 

typewriter Code examples and code fragments. 

% bold typewriter In interactive examples, user input is shown in bold typewriter 
typewriter and system output is shown in regular typewriter font. 
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Customer Support 


Thinking Machines Customer Support encourages customers to report errors in Connection Machine 
operation and to suggest improvements in our products. 

When reporting an error, please provide as much information as possible to help us identify and 
correct the problem. A code example that failed to execute, a session transcript, the record of a back¬ 
trace, or other such information can greatly reduce the time it takes Thinking Machines to respond 
to the report. 

If your site has an Applications Engineer or a local site coordinator, please contact that person direct¬ 
ly for support. Otherwise, please contact Thinking Machines’ home office customer support staff: 


U.S. Mail: Thinking Machines Corporation 

Customer Support 
245 First Street 

Cambridge, Massachusetts 02142-1264 

Internet 

Electronic Mail: customer-support@think.com 


UUCP 

Electronic Mail: ames!think! customer-support 

Telephone: (617) 234-4000 

(617) 876-1111 


For Symbolics Users Only 

The Symbolics Lisp machine, when connected to the Internet network, provides a special mail facil¬ 
ity for automatic reporting of Connection Machine system errors. When such an error occurs, simply 
press Ctrl-M to create a report. In the mail window that appears, the To: field should be addressed 
as follows: 


To: customer-support@think.com 

Please supplement the automatic report with any further pertinent information. 
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Chapter 1 

The Image File Interface 


1.1 Overview 

The Image File Interface allows you to store image data from the CM system in files for 
later display or processing. This interface includes routines to transfer image data to and 
from an image data file and 

■ an image buffer in CM memory 

■ an array on the front-end computer 

■ a generic display (i.e., a CM framebuffer or an XI1 window initialized as a Generic 
Display Interface display) 

The Image File Interface writes and reads files that conform to the the TIFF (Tagged Image 
File Format) 5.0 specification as published by Aldus Corporation and Microsoft Corpora¬ 
tion. This format is accepted by many other graphics systems and software packages on 
platforms ranging from personal computers to supercomputers. Thus, this interface makes 
it possible for you to move images between the CM system and many other graphics 
environments. 

The TIFF format allows you to store image data in a compressed format and also to store 
information about the image and its display environment in the file. When the image is later 
read back into the CM system by the Image File Interface, or read by another TIFF reader 
elsewhere, this information allows the software to interpret and display the data correctly. 


1.1.1 Including Image File Interface Routines in a Program 

To use the Image File Interface routines, you must include the appropriate header file in 
your program and link with the supporting libraries when compiling. 
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For C/Paris programs you must 

■ include the the header file cmtif f. h: 

#include <cm/cmtiff.h> 

■ use the following links: 

cc prog.c -lcmsr -ltiff -1X11 -lparis -lm 

For Fortran/Paris programs you must 

■ include the the header file cmtif f-fort. h: 

INCLUDE '/usr/include/cm/cmtiff-fort.h> 

■ use the following links: 

f77 prog.f -lcmsr -ltiff -1X11 -lparisfort -lparis -lm 

For Lisp programs you must use a band in which the graphics package has been loaded. 
If necessary, you can load it by entering 

(lcmw:load-optional-system 'graphics) 


1.2 Image Transfer 

The Image File Interface provides a simple functional interface to read or write image data 
between a TIFF-formatted file and an image buffer, a front-end array, or a generic display. 


1.2.1 Writing an Image to a File 

For example, to store an image from a generic display in a TIFF-formatted file, you can use 
a single CMSR (CM *Render) subroutine call: 

CMSR_image_display_to_file_simple 

( filename, append_p, width, height) 
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This routine writes an image array from the currently selected generic display to the file 
named. The area of the display transferred is an array of width by height pixels, beginning 
from the point defined by any Generic Display Interface offsets in effect for the display, 
or from the origin of the display space if no offsets are set. If append_p is true (.TRUE, in 
Fortran, non-NULL in C, non-nil in Lisp), the image is added to the end of the file after any 
other images already stored there; if append_p is false (.FALSE, in Fortran, NULL in C, nil 
in Lisp), this image overwrites any that may be in the file. CMSR_image_display_ 
to_f ile_simple also reads information about the image, such as pixel depth and color 
type, from the Generic Display and stores it in the file with the image data. A default com¬ 
pression strategy is used to store the image data. 

Two similar routines write images to a file from an image field in CM memory and from 
an image array in the front-end computer’s memory: 

■ CMSR__image_f ield__to_f ile_s imple 

(* filename, srcJield, slen, appendjp, xjyaries _fastest_p, width, height, 
photometric Jnterpretation, samples_per_pixel, bits_per_sample, 
red[ ], green[ ], blue[ ]) 

■ CMSR_image_array_to_file__simple 

(* filename, *image_array, append _p, width, height, 
photometric Jnterpretation, samples _per_pixel, bits _per_sample, 
red[ ], green[ ], blue[ ]) 

Because these routines cannot determine the image characteristics as CMSR_image__dis- 
play_to_filejsimple can from the generic display, you must specify the essential 
image information as arguments to the routine. 

To avoid specifying these parameters each time you save an image, you can use one of a 
set of routines that use an image information structure to define the image characteristics 
and also allow you to control the compression and configuration strategies used to store the 
image data in the file: 

■ CMSR__image__ar r ay_to_f i le 

(* filename, *image_array, image Jnfo, append_p) 

■ CMSR_image_di sp 1 ay_t o__f i 1 e (*filename, image Jnfo, appendjp) 

■ CMSR__image__f ie 1 d__to_f i 1 e 

(*filename, srcJield, slen, image Jnfo, appendJp, xjyaries Jastest_p) 

The image information structure is an Image File Interface data structure used to maintain 
information about the type of image to be stored and way the data is to be organized in the 
file. In addition, you can record the image artist, date and time of creation, the host comput- 
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er, and the software used. The Image File Interface provides routines that allocate this 
structure, and that set and read back its parameters. This allows you to control the way the 
image is stored, for example, to match the characteristics of another TIFF reader. See Sec¬ 
tion 1.3 below for a more detailed discussion. 


1.2.2 Reading an Image from a File 

A similar set of routines transfers image data from a TIFF-formatted file to a CM field, an 
array on the front-end computer, or directly to a generic display: 

■ CMSR_image_file_to_field 

(* filename, destJield, dlen, image info, imagenumber, x varies __ fastest_p) 

■ CMSR_image_file_to_array 

(* filename, image array, image info, image number) 

■ CMSR_image_file_to_display (* filename, imageinfo, image number) 

CMSR_image_file_to_field and CMSR_image_file_to_array read the image by 
transferring each pixel’s data from the file to the corresponding element of the 2D field or 
array. CMSR_image_file_to_display transfers the image data to the currently selected 
generic display beginning at the origin (0,0) of the display space or at the point specified 
by any Generic Display Interface offsets that may be set. 

The image info argument specifies an image information structure. When these routines 
read in the image, they also load the image_ info structure with the information about the 
image stored in the TIFF file. The Image File Interface then uses this information to inter¬ 
pret the image data properly. You can also access the information to configure your display 
environment. If you leave the image info argument as NULL or zero, the image info argu¬ 
ment is ignored and no data describing the image is returned. 

If more than one image is stored in the file, the imagejiumber argument specifies which 
image is to be returned. 


1.2.3 Image Transfer Commands 

In addition, two shell-level commands allow you transfer an image between a file and a CM 
framebuffer generic display: 
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■ cmdisplay2tiff [-append] [-x offset] [-y offset ] [-w width] 

[-h height] [-artist name ] [-host name] 
[-description string] [-software name] 
[-separate] [-nocomp | -lzw] 
[-rowsperstrip number] filename 

■ tiff2cmdisplay [-x offset] [-y offset] [-image number] 

[-v] [-nozoom] [-nowait] filename 


1.3 The Image Information Structure 

The Image File Interface routines use the image information structure to interpret data 
when transferring images to or from an image file. When an image is written from the CM 
system to a file, the transfer routines use this information to organize the image data in the 
file and then store it with the image data. When a stored image is read back into the CM 
system, these routines automatically load this information into an image information struc¬ 
ture and you can use it to configure the display or array to which the image is sent. 

If you usually use a standard image definition and file format or have a series of similarly 
defined images to store, the image information structure allows you to define a standard set 
of specifications that can be referenced by the Image File Interface routines. If you have 
only a small number of images of a certain type, the image transfer routines ending in 
-simple do not require an image information structure. These routines allow you to spec¬ 
ify a minimum number of defining parameters as arguments. 

The Image File Interface provides routines to allocate and deallocate this structure: 

■ CMSR_allocate_image_inf o ( ) 

■ CMSR__deallocate_image_inf o ( image_info) 

A routine is also provided that reads the image information from a file into an image infor¬ 
mation structure: 

■ CMSR_image__get_info (filename , image_info, imagejiumber) 
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1.3.1 Image Attributes Information 

An image is described in the image information structure by 

■ image width and height in pixels 

■ number of color samples per pixel 

■ number of bits per sample 

■ photometric interpretation: how the image samples are to be interpreted 

■ color map arrays to be installed with the image. 

You use Image File Interface routines to set these parameters and to return the current 
setting. 


Image Width and Height 

The image width is set by CMSR_image_set_width (image_info, width) and the current 
setting of image width is returned by CMSR_image_width (image Jnfo) . Similarly, the 
image height is set by CMSR_image_set_height (imageJnfo, height) and returned by 
CMSR_image_height ( image Jnfo) . The width of the image is the number of pixels in the 
horizontal (jc) dimension and the height is the vertical (y) dimension in pixels. 


Color Samples 

The number of color samples per pixel is set by CMSR_image_set_num_sample 
(imageJnfo, samples_perjpixel) and returned by CMSR_image_num_samples 
(image_ info) . The number of samples is the number of color components maintained for 
each pixel. For example, monochrome, grayscale, and pseudo-color images all maintain 
one sample per pixel, while true color (direct color) images maintain three samples, usually 
red, green, and blue. 

The number of bits per sample is set by CMSR_image_set_bits_per_ 
sample (imageJnfo, bits_per_sample) and returned by CMSR_image_bits_per_ 
sample (imageJnfo) . The number of bits per sample specifies the size of each compo¬ 
nent. For example, a monochrome image is defined in 1 bit per sample; grayscale or pseudo 
color images are often 8 bits per sample: RGB images are usually composed of three 8-bit 
samples. (For images composed of more than one sample per pixel, the Image File Inter¬ 
face requires that the number of bits be the same for all the samples.) 
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Photometric Interpretation 

The photometric interpretation indicates how the pixel data is to be interpreted. For exam¬ 
ple, an image with one sample per pixel and 8 bits per sample may be interpreted as either 
a grayscale or a palette (pseudo color) image. This parameter is set by CMSR_image_set_ 
photometric (image_info, photometric) and returned by CMSR_image_pho tome trie 
(image info) . 

The TIFF photometric interpretations supported by the Image File Interface are 

■ photometric_miniswhite and photometric_minisblack for monochrome 
and grayscale images. These values specify whether the minimum value in the col¬ 
or map is white or black. 

■ PHOTOMETRIC_Palette indicates the image will contain one sample per pixel, 
which is interpreted as an index into a color map. 

■ photometriC_rgb indicates three or four samples per pixel. The first three sam¬ 
ples are interpreted as the red, green, and blue intensities of the color. You can use 
the fourth sample for whatever purpose you wish. For example, the fourth sample 
may be used to store z-buffer values or a transparency mask. 


Color Map 

You must specify a color map for images with a photometric_palette photometric 
interpretation. The color map is set with CMSR_image_set_color_map (image info, red, 
„ green, blue) and the color map currently set in an image information structure is returned 
with CMSR_image_co 1 or_map (image info). 

When you transfer a palette color image to a generic display, the display is automatically 
set to the color map stored with the image in the red, green, and blue arrays. 


1.3.2 Image Environment Notes 

In addition to the image attributes, you can store information about the context in which 
the image was created as a part of the TIFF file itself. 

The image information structure accepts character strings in which you can record 

■ the image artist 

■ date and time the image was created 
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■ host computer (computer on which the image was created) 

■ software used to create the image 

■ text description of the image 

As with the attributes, there are routines to set and read back each of these fields: 

■ CMSR_image_set_artist ( imageinfo, * string) 
CMSR_image_artist ( image_info) 

■ CMSR_image_set_date_time (image info, * string ) 
CMSR_image_date_time (image_info) 

* CMSR_image_s e t_ho s t_c ompu te r ( imageinfo, * string) 
CMSR_image_hos t_computer ( imageinfo) 

■ CMSR_image_s e t_s o f twar e (image info, * string) 

CMSR_image_s of tware ( imageinfo ) 

■ CMSR_image_set_description (image_info, * string) 
CMSR_image_des cription ( image info ) 


1.3.3 File Format Information 

Information about the file format that is stored for TIFF files includes 

■ compression strategy 

■ planar configuration (how the color planes are to be organized in the file) 

■ rows per strip (the number of rows [scanlines] of image data to be stored for each 
strip of data in the file) 

Compression Strategy 

The compression parameter allows you choose to store the image data in the file in a com¬ 
pressed format or not. 
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The compression parameter lets you select different compression strategies depending on 
the device that will be used to read the file. The supported compression strategies are 

■ COMPRESSION_LZW 

■ COMPRESSION_NONE 

The default is the general compression strategy lzw . lzw uses the Lempel-Ziv and Welch 
algorithm for data compression. This is a general purpose algorithm that works well on any 
type of image. The algorithm is described in detail in Appendix F of the TIFF (Tagged 
Image File Format) 5.0 specification as published by Aldus Corporation and Microsoft 
Corporation. (See Section 1.5) 

Most other TIFF readers accept the LZW compression strategy. However, if you are transfer¬ 
ring the image to another graphics environment, check on the compression strategies 
supported by the software you will be using there. If you do not know what compression 
methods are supported, we recommend no compression (NONE). Images stored with no 
compression should be acceptable to nearly all TIFF readers. 


Planar Configuration 

The configuration parameter describes how image data that contains more than one sample 
per pixel is to be stored. The configuration strategy is set with CMSR_image_set_ 
planar_config (imagejnfo, configuration) and returned with CMSR_image_planar_ 
config (image info). 

The image samples can be stored either as a contiguous array (PLANARCONFIG_CONTIG) 
or as one array for each separate plane of samples (PLANARCONFlG_SEPARATE). For ex¬ 
ample, an RGB image stored contiguously would have the samples interleaved: 
RGBRGBRGB.... The same image stored separately would have one plane for the red sam¬ 
ples, another for the green samples, and a third for the blue samples. 

Your choice of configuration methods will depend on whether you will be porting the 
image to other software and what compression strategy you wish to use. Some software 
packages will only accept contiguous images because each pixel’s values are available in 
sequence. However, many compression strategies work more efficiently when the color 
samples are stored in separate planes. 

The configuration parameter is not used for images with only one sample per pixel. 
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Rows per Strip 

The rows per strip parameter describes the number of rows (scanlines) of image data that 
is to be stored for each strip of data in the image file. The number is set with 
CMSR_image_set_rows_per_strip (image_info, rows_per_strip) and returned with 
CMSR_image_rows_per_strip ( image_info). 

This parameter allows you to control the amount of data that will be sent with each read 
from the file. This should be adjusted to allow efficient buffering on your system. If not 
specified, the Image File Interface sets the parameter to result in about 8K of data being 
buffered at a time. 


1.4 Supported TIFF Classes 

The following lists the TIFF image classes supported by the Image File Interface. 


TIFF Class B (Bilevel/Monochrome) 

■ Samples per pixel: 1 

■ Bits per sample: 1 

■ Photometric Interpretation: PHOTOMETRIC_MlNISWHITE or 
PHOTOMETRIC_MINISBLACK 

■ Compression: compression_none or compression_lzw 

This photometric indicates whether the low entry in the color map is black or white. For 
photometric_miniswhite , for example, pixels with a value of 0 are displayed as white 
and pixels with a value of 1 are black. 


TIFF Class G (Grayscale) 

■ Samples per pixel: 1 

■ Bits per sample: 4 or 8 

■ Photometric Interpretation: photometric_miniswhite or 
PHOTOMETRIC MINISBLACK 
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■ Compression: compression_none or compression_lzw 

This photometric indicates whether the low entry in the color map is black or white. For 
photometric_miniswhite, for example, the color ramp is a range of gray intensities 
running from white at 0 to black at the maximum color map entry. 


TIFF Class P (Palette, Pseudo Color) 

■ Samples per pixel: 1 

■ Bits per sample: 1, 2, 4, 8 

■ Photometric Interpretation: PHOTOMETRIc_palette 

■ Compression: compression_none or compression_lzw 

When photometric interpretation is set to indicate a palette color image, you must also sup¬ 
ply a color map. 

NOTE: The TIFF 5.0 specification allows for any number of bits per sample in the palette 
class from 1 to 8. The Image File Interface supports only 1, 2,4, or 8 bits, as listed above. 


TIFF Class R (RGB Full Color) 

■ Samples per pixel: 3 or 4 

■ Bits per sample: 8 

■ Photometric Interpretation: PHOTOMETRIC_RGB 

■ Compression: COMPRESSlON_NONE or COMPRESSION_LZW 

NOTE: TIFF 5.0 specifies only 3 samples for the Class R images. The Image File Interface 
extends this to allow four samples. When an image with a photometric interpretation of 
PHOTOMETRIC_RGB and four samples is transferred to a CM field or front-end array, the 
fourth sample is simply written to memory following the other three samples. You must 
have allocated sufficient memory for the additional sample. If the image is transferred to 
a generic display, the fourth sample is not used. You may use the fourth sample in your 
application in any way you wish, for example, as a z-buffer or a transparency mask. 
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1.5 TIFF 5.0 Information 

For detailed information on the TIFF 5.0 specification, contact either of the following: 

■ Developer’s Desk, Aldus Corporation 
411 First Ave. So., Suite 200 Box 97017 

Seattle, WA 98104 Tel: (206) 622-5500 

■ Windows Marketing Group, Microsoft Corporation 
16011 NE 36th Way 

Redmond, WA 98073-9717 Tel: (206) 882-8080 

Much of the Image File Interface is built on top of a library of support routines that manipu¬ 
late TIFF files. This library, along with several useful tools and test images, is available by 
anonymous ftp. 

To retrieve a copy, you can use ftp to connect to either ucbvax.berkeley.edu 
(128.132.130.12) oruunet.uu.net (192.48.96.2) . From ucbvax, you should re¬ 
trieve the file pub/tiff/v2.4. tar . Z, from uunet retrieve graphics/tiff. tar . Z . 
Please remember that these machines are heavily used, and try to retrieve files from them 
outside of normal business hours. 

The file that you get will be a compressed tar file, so remember to set binary mode when 
using ftp. For example: 

% ftp ucbvax.berkeley.edu 

Connected to ucbvax.berkeley.edu. 

220 ucbvax.Berkeley.EDU FTP server 

Name (ucbvax.berkeley.edu:matt): anonymous 
331 Guest login ok, send ident as password. 

Password: 

230 Guest login ok, access restrictions apply. 
ftp> binary 
200 Type set to I. 
ftp> get v2.4.tar.Z 

200 PORT command successful. 

150 Opening BINARY mode data connection for v2.4.tar.Z (333827 bytes). 

226 Transfer complete. 

local: v2.4.tar.Z remote: v2.4.tar.Z 

333827 bytes received in 25 seconds (13 Kbytes/s) 

ftp> quit 

221 Goodbye. 


The software comes in a compressed tar file. To extract the information: 
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Chapter 2 

Image File Operations 


This chapter provides detailed descriptions of the Image File Interface routines divided into 
two groups: 

■ Image File Transfer routines (beginning immediately below) 

■ Image Information Structure routines (beginning on page 44) 


2.1 Image Transfer Routines 

This section describes the Image File Transfer routines that read and write files between 
the CM system and an image file. 

The Image File Transfer routines read and write files between the CM system and an image 


file. These routines are: 

CMSR_image_array_to_file. 15 

Transfers an image from a front-end array to a TIFF file using an image 
information structure. 

CMSR_image_array_to_file_simple . 18 

Transfers an image from a front-end array to a TIFF file without using an 
image information structure. 

CMSR_image_display_to_file . 22 

Transfers an image from current CM Generic Display to a TIFF file using 
an image information structure. 

CMSR_image_disp_to_fi le_s imple. 24 


Transfers an image from current CM Generic Display to a TIFF file without 
using image information structure. 
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CMSR_image_field_to_file. 26 

Transfers an image from CM memory to a TIFF file using an image 
information structure. 

CMSR_image_field_to_file_simple . 29 

Transfers an image from CM memory to a TIFF file without using an image 
information structure. 

CMSR_image_file_to_array. 33 

Transfers an image from a TIFF file to a front-end array. 

CMSR_image_file_to_display . 35 

Transfers an image from a TIFF file directly to the current generic display. 

CMSR_image_file_to_field. 37 

Transfers an image from a TIFF file to an image buffer field in CM memory. 

cmdisplay2tiff . 40 

Copies an image from a CM framebuffer generic display to a TIFF file. 

tif£2cmdisplay . 42 

Copies an image from a TIFF file to a CM framebuffer generic display. 
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CMSR_image_array_to_file 


CMSR_image_array_to_file 

Transfers an image from a front-end array to an image file. 


SYNTAX 
C Syntax 

#±nclude <cm/cmti£f .h> 


int 

CMSR_image_array__to_jf i 1 e 

(*filename, *image_array, image info, append_p) 


char 

CMSR_generic_j>ointer__t 
CMSR_image_inf o_t 
int 


* filename ; 
image_array; 
imageinfo; 
append_p; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 


INTEGER FUNCTION CMSR_IMAGE_ARRAYJTO__FILE 

& {filename, image array, image_info, appendjp) 


CHARACTER* (*) 
ANY_FE_ARRAY 
INTEGER 
LOGICAL 


filename 
image_array 
image_info 
appendjp 


ARGUMENTS 

filename The name of the file to which the image is to be written. 

image array The front-end array from which the image is to be read. The image 

array may be of any data type. The array elements will be 
interpreted as image pixels according to the values provided in the 
fields for width , height , samples_per jiixel, bits_per_sample , and 
photometric interpretation in the image information structure. 
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In C the CMSR_generic_pointer_t data type accepts a pointer 
to any data type. It is used to make code portable between ANSI 
compilers that accept pointers to void and VAX compilers that 
would require a pointer to char for unspecified data types. You 
may need to cast this variable to the data type you use for your 
array to avoid compiler warnings. 

imageinfo A CMSR_image_inf o_t data structure containing specifications 

for the image and for the format in which it is to be stored. 

Image information structures are created with CMSR_allocate_ 
image_info. 

NOTE: There are no defaults in the image information structure 
for width, height, photometric interpretation, numsamples, or 
bits_per_sample. Before you write an image you must make sure 
that these fields are set correctly by calling the appropriate Image 
File Interface Routine: 

■ CMSR_image_set_width 

■ CMSR_image_set_height 

■ CMSR_image_s e t_num_s amp le s 

■ CMSR_image_set_bits_per_sample 

■ CMSR_image_set_photometric 

appendjp A predicate indicating whether the image is appended to filename 

or overwrites filename. If append_p is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp) the image from the array is 
appended to the end of the file. If append_p is false (.FALSE, in 
Fortran, NULL in C, nil in Lisp), the image from the field 
overwrites any images already in the file. 


DESCRIPTION 

CMSR_image_array_to_file transfers an array on the front-end computer to an 
image file. 

The image array may be of any data type. But, before writing the contents of the array 
to a TIFF file, the image Jnfo structure must be set to describe that image. At a mini¬ 
mum, this means that the width, height, samples per pixel, bits per sample, and 
photometric interpretation must be specified. 
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CMSR_image_array_to_file 

CMSR_image_array_to_f i 1 e returns non-negative integers on success and 
CMSR_lMAGE_ERROR if an error is detected. 

ERRORS 

An error is signalled if 

the specified file can not be opened for writing 
an error occurs while writing scanlines to the file 

SEE ALSO 

CMSR_image_array_to_file_simple 
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CMSR_image_array_to_file_simple 

Transfers a front-end array to an image file. 


SYNTAX 
C Syntax 

♦include <cm/cmtiff.h> 
int 

CMSR_image_ar r ay_jto_f ile_ s imple 

(*filename, *imagejarray, append_p, width, height, 
photometric-interpretation, 

samples_per_pixel, bits_per_sample, red, green, blue) 


char 

CMSR__genericjpointer_jt 

int 

int 

int 

int 

float 


* filename; 

image jar ray; 

append_p; 

width, height ; 

photometric-interpretation; 

samples_per jjixel, bitsjersample; 

red [ ] , green [ ] , blue [ ] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 


INTEGER FUNCTION CMSRJTMAGE_ARRAYJTO_FILE_JSIMPLE 

& (* filename, *image_array, append_p, width, height, 

& photometric interpretation, 

& samples_perjpixel, bits_per_sample, red, green, blue) 


CHARACTER* (*) 

ANY_FE_ARRAY 

LOGICAL 

INTEGER 

INTEGER 

INTEGER 

REAL 


filename 
image_array 
append_p 
width, height 

photometric-interpretation 
samples_per jpixel bits j>er_s ample 
red () , green () , blue () 
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CMSR_image_array_to_file_simple 


ARGUMENTS 

filename The name of the file to which the image is to be written. 

image array The front-end array from which the image is to be read. The image 

array may be of any data type. The array elements will be 
interpreted as image pixels according to the values provided for 
width, height, samplesjper_pixel, bits_per_sample, and 
photometric interpretation. 

In C the CMSR_genericjpointer_t data type accepts a pointer 
to any data type. It is used to make code portable between ANSI 
compilers that accept pointers to void and VAX compilers that 
would require a pointer to char for unspecified data types. You 
may need to cast this variable to the data type you use for your 
array to avoid compiler warnings. 

append_p A predicate indicating whether the image is appended to filename 

or overwrites filename. If append _p is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp), the image from the array is 
appended to the end of the file. If append_p is false (.FALSE, in 
Fortran, NULL in C, nil in Lisp), the image from the field 
overwrites any images already in the file. 

width An integer specifying the number of pixels in the image’s x 

(horizontal) dimension. 

height An integer specifying the number of pixels in the image’s y 

(vertical) dimension. 

photometric interpretation 

An enumerated variable specifying how the image data is to be 
interpreted by Image File Interface. 

Possible values can be: 

■ PHOTOMETRIC_MINISWHITE 

■ PHOTOMETRIC_MINISBLACK 

■ PHOTOMETRIC_RGB 

■ PHOTOMETRIC_PALETTE 

samples_per jpixel The number of color components that are maintained per pixel in 
the image to be stored. Currently, the number of samples sup¬ 
ported by the Image File Interface is the following: 
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■ 1 for bilevel, grayscale, or palette images or image masks 

■ 3 (red, green, and blue) for RGB true color images 

■ 4 (red, green, blue, and alpha) for RGB plus alpha channel 
images 

bitsjper_sample The number of bits of color information maintained for each 

sample per pixel in the image. For one sample per pixel the bits 
per sample may be 1, 2, 4, or 8. 

For three or four samples per pixel, the bits per sample must be 8. 
For the most common classes of images, the following numbers 
of bits per sample are supported: 

■ Bilevel images must be 1 bit per sample 

■ Grayscale images can be 4 or 8 bits per sample 

■ Palette color images can be 1,2, 4, or 8 bits per sample 

■ RGB full-color images must be 8 bits per sample 

■ RGB plus alpha images must be 8 bits per sample 

red, green, blue Arrays of color values specifying the red, green, and blue 
components of a color map. The arrays must each have 
2 A (samples_per pixel) elements. 

If the photometric interpretation is PHOTOMETRIC_PALETTE , the 
color map must be specified. For palette images, the color map is 
stored in the file with the image. 

NOTE: If you want to load a color map from a generic display, you 
can use the Generic Display Interface routine CMSR_display_ 
read_color_map. 


DESCRIPTION 

CMSR_image_array_to_file_s imple transfers an image array on the front-end 
computer to an image file. 

This routines returns non-negative integers on success and CMSR_lMAGE_ERROR if an 
error is detected. 
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CMSR_image_array_to_file_simple 

ERRORS 

An error is signalled if 

the specified file cannot be opened for writing 
an error occurs while writing scanlines to the file 

SEE ALSO 

CMSR_image_array_to_file 
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CMSRJmage_display__to_file 

Transfers an image from current CM Generic Display to a specified image file. 

SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
int 

CMS R_image_di sp 1 ay_to_f i 1 e 

(* filename, imageJnfo, append_p) 

char * filename; 

CMSR_jLmage_JLnf o__t image Jnfo; 
int append_p; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

INTEGER FUNCTION CMSR_IMAGE__DISPLAY JTO_FILE 

& ( filename, imageJnfo , append_p) 

CHARACTER*(*) 

INTEGER 
LOGICAL 


ARGUMENTS 

filename The name of the file to which the image is to be written. 

image Jnfo A CMSR_jLmage_jLnf o__t data structure containing specifications 

for the image and for the format in which it is to be stored. 

append jp A predicate indicating whether the image is appended to filename 

or overwrites filename . If append_p is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp), the image from the array is 
appended to the end of the file. If append_p is false (.FALSE, in 
Fortran, NULL in C, nil in Lisp), the image from the field 
overwrites any images already in the file. 


filename 
image Jnfo 
append_p 
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DESCRIPTION 

CMSR_image_display_to_f ile transfers an image directly from the current 
Generic Display display to an image file. 

If the image info structure does not contain entries for the image’s width, height, bits 
per sample, samples per pixel, or photometric interpretation, these are determined from 
the currently selected generic display. 

If the photometric interpretation is photometric_palette, the color map of the 
Generic Display display is stored with the image. 

CMSR_image_display_to_file returns non-negative integers on success and 
CMSR_lMAGE_ERROR if an error is detected. 

SEE ALSO 

CMSR__image_di sp__to_f i 1 e_s impl e 
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CMSRJmage_disp__to_file_simple 

Transfers an image from current CM Generic Display to a specified image file without 
using image information structure. 


SYNTAX 
C Syntax 

#include <cm/cmtiff ,h> 
int 

CMSR__image__di sp__to__f ile_js ixnple 

(* filename, append_p, width, height) 


char * filename; 
int append_p; 

int width, height; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort> h' 


& 


INTEGER FUNCTION CMSRJCMAGEJDISPJTOJFILEJSIMPLE 

( filename, append_p, width, height) 


CHARACTER* (*) 

LOGICAL 

INTEGER 


filename 
appendjp 
width, height 


ARGUMENTS 

filename The name of the file to which the image is to be written. 

The filename parameter must point to an area of memory large 
enough to hold the image. 

append_p A predicate indicating whether the image is appended to filename 

or overwrites filename . If append_p is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp), the image from the array is 
appended to the end of the file. If appendjp is false (.FALSE, in 
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Fortran, NULL in C, nil in Lisp), the image from the field 
overwrites any images already in the file. 

width An integer specifying the number of pixels in the image’s x 

(horizontal) dimension. 

height An integer specifying the number of pixels in the image’s y 

(vertical) dimension. 


DESCRIPTION 

CMSR_image_disp_to_file_simple transfers an image directly from the current 
Generic Display display to an image file. 

The photometric interpretation is determined from the current Generic Display. 

This routine returns a non-negative integer on success and CMSR_IMAGE_ERROR if an 
error is detected. 


SEE ALSO 

CMSR_image_di spl ay_t o_f i le 
cmdisplay2tiff 
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CMSRJmage_field_to_file 

Transfers an image from CM memory to a file using an image information structure. 

SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
int 

CMSR__image__f ield_to__f i le 

(* filename, src Jeld, srcjen, image info, append_p, 
x_varies_fastest_p) 

char * filename ; 

CM_field_id_t srcJield; 

unsigned int srcjen; 

CMSR_image_jLnfo__t image_info; 

int append_p ; 

int x_yaries Jastest_p; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

INTEGER FUNCTION CMSRJEMAGE_FIELD_TO_FILE 

& ( filename, srcJeld, srcjen , imageJnfo, append_p, xjvariesJastestj?) 

CHARACTER* (*) 

INTEGER 
INTEGER 
INTEGER 
LOGICAL 
LOGICAL 


ARGUMENTS 

filename The file to which the image is to be written. 

src Jield The field ID of the field in CM memory from which the image is 

to be read. 


filename 
src Jeld 
srcjen 
image Jnfo 
append_p 
xjyaries Jastest_p 
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srcjen 
image info 


appendp 


xvariesfastest_p 


CMSR_image_field_to_file 


The length, in bits, of the source field containing the image. 

A CMSR_image_info_t data structure containing specifications 
for the image and for the format in which it is to be stored. 

Image information structures are created with CMSR_allocate_ 
image_info. 

NOTE: There are no defaults in the image information structure 
for width, height, photometric Jnterpretation, num_samples, or 
bits_per_sample. Before you write an image you must make sure 
that these fields are set correctly by calling the appropriate Image 
File Interface routine: 

■ CMSR_image_set_width 

■ CMSR_image_set_height 

■ CMSR_image_set_num_samples 

■ CMSR_image_set_bits_per_sample 

■ CMSR_image_set_photometrie 

A predicate indicating whether the image is appended to filename 
or overwrites filename. If appendj> is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp), the image from the array is 
appended to the end of the file. If append_p is false (.FALSE, in 
Fortran, NULL in C, nil in Lisp), the image from the field 
overwrites any images already in the file. 

A boolean or logical specifying whether the image is stored such 
that the x or y coordinate varies fastest. Normally, x_varies_ 
fastest_p should be set to true. 

If xjyariesfastest_p is true (.TRUE, in Fortran, non-NULL in C, 
non-nil in Lisp), the image data is organized so that the x 
coordinate varies fastest, that is, in column-major order. This is 
the case for Fortran language arrays, and for C arrays that are 
referenced [y][x]. 

If x_varies Jastest_p is false (.FALSE, in Fortran, NULL in C, nil 
in Lisp), the image data is organized so that they coordinate varies 
fastest, that is, in row-major order. This is the case for C arrays 
referenced [x][y]. 

The * Render display routines assume that x varies fastest and 
maps axis 0 of the image field to the x dimension of the display. 
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If your image arrays are stored so that y varies fastest, 
x_yaries Jastest should be set to FALSE. 


DESCRIPTION 

CMSR_image_f ield_to_f ile transfers an image directly from the specified field in 
CM memory to an image file using the current settings of the image info structure. 

Before calling this routine, an image information structure must be allocated and the 
parameters for the image width, height, samples per pixel, bits per sample, and photo¬ 
metric interpretation must be set. If the photometric interpretation is palette, you must 
also supply a color map. See the description of the Image File Interface routines that set 
these parameters for more information. 

CMSR_image_f i e 1 d_to_f ile returns non-negative integers on success and 
CMSR_IMAGE_ERROR if an error is detected. 

SEE ALSO 

CMSR_image_field_to_file_simple 
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CMSRJmage_field_toJFile_simple 


CMSRJmage_field_to_file_simple 

Transfers an image from CM memory to a file without using an image information struc¬ 
ture. 


SYNTAX 
C Syntax 


#include <cm/cmtiff.h> 


int 

CMSR_image_jf ield_to_f ile__s imple 

(*filename, srcJield, srcjen, append_p, xjyaries_fastest_p, width, height, 
photometric Jnterpretation, samples_per jpixel, bits_per_sample, red, 
green, blue) ; 


char 

CM_f i e 1 d__i d__t 

unsigned int 

int 

int 

int 

int 

int 

float 


* filename; 
srcJield; 
srcjen ; 
append_p; 
x_yaries Jastest_p; 
width, height; 

photometric Jnterpretation; 
samples_per_pixel, bits_per_sample; 
red [ ] , green [ ] , blue [ ] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

INTEGER FUNCTION CMSR___IMAGE_FIELD_TO_FILE_S IMPLE 

& (filename, srcJield, srcjen, append_p, xjyariesJastest_p, width, height, 

& photometric Jnterpretation, samples _per_pixel, bits _per_sample, red, 

& green, blue) 

CHARACTER* (*) 

INTEGER 
INTEGER 
LOGICAL 
LOGICAL 
INTEGER 
INTEGER 


filename 
srcJeld 
srcjen 
append_p 
xjyaries Jastest_p 
width, height 

photometric Jnterpretation 
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CMSR_image_field_to. 

INTEGER 

REAL 


ARGUMENTS 

filename 

srcJield 

srcjen 
append_p 


xvariesfastest_p 


width 

height 

30 


file_simple 


samples_per_pixel, bits_per_sample 
red () , green () , blue () 


The file to which the image is to be written. 

The field ID of the field in CM memory from which the image is 
to be read. 

The length, in bits, of the source field containing the image. 

A predicate indicating whether the image is appended to or 
overwrites filename. If append_p is true (.TRUE, in Fortran, 
non-NULL in C, non-nil in Lisp), the image from the array is 
appended to the end of the file. If append j) is false (.FALSE, in 
Fortran, NULL in C, nil in Lisp), the image from the field 
overwrites any images already in the file. 

A boolean or logical specifying whether the image is stored such 
that the x or y coordinate varies fastest. Normally, x_yaries_ 
fastest_p should be set to true. 

If x_varies Jastest_p is true (.TRUE, in Fortran, non-NULL in C, 
non-nil in Lisp), the image data is organized in the file so that the 
x coordinate varies fastest, that is, in column-major order. This is 
the case for Fortran language arrays, and for C arrays that are 
referenced [y][x]. 

If x_variesJastestp is false (.FALSE, in Fortran, NULL in C, nil 
in Lisp), the image data is organized so that the y coordinate 
varies fastest, that is, in row-major order. This is the case for C 
arrays referenced [x][y]. 

The *Render display routines assume that the x coordinate varies 
fastest and maps axis 0 of the image field to the x dimension of the 
display. If your image arrays are stored so that y varies fastest, 
xjyaries Jastest should be set to FALSE. 

If x_varies Jastest_p is true, width is the length of axis 0 of the 
field. If x_varies Jastest_p is FALSE, width is the length of axis 1. 

If x_varies Jastest_p is true, height is the length of axis 1 of the 
field. If x_yaries Jastest_p is FALSE, height is the length of axis 0. 
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photometricJnterpretation 

An enumerated variable specifying how the image data is to be 
interpreted by Image File Interface. 

Possible values can be: 

■ PHOTOMETRIC_MINISWHITE 

■ PHOTOMETRIC_MINISBLACK 
* PHOTOMETRIC_RGB 

■ PHOTOMETRIC_PALETTE 

samples_per jpixel The number of color components that are maintained per pixel in 
the image to be stored. Currently, the number of samples 
supported by the Image File Interface are 

■ 1 for bilevel, grayscale, or palette images 

■ 3 (red, green, and blue) for RGB true color images 

■ 4 (red, green, blue, and alpha) for RGB plus alpha channel 
images 

bitsjper sample The number of bits of color information maintained for each 

sample per pixel in the image. For one sample per pixel the bits 
per sample may be 1,2,4, or 8. For three or four samples per pixel 
the bits per sample must be 8. For the most common classes of 
images, the following numbers of bits per sample are supported: 

■ Bilevel images must be 1 bit per sample 

■ Grayscale images can be 4 or 8 bits per sample 

■ Palette color images can be 1,2, 4, or 8 bits per sample 

■ RGB lull-color images must be 8 bits per sample 

■ RGB plus alpha images must be 8 bits per sample 

red, green, blue Arrays of color values specifying the red, green, and blue 
components of a color map. The arrays must each have 
2 A {samples_per_pixel) elements. 

If the photometric interpretation is PHOTOMETRlC_PALETTE, 
these arrays must be specified. For palette images, the color map 
defined by these arrays is stored in the file with the image and 
used to initialize the Generic Display when the file is read back 
into the system. 
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If photometric interpretation has any value other than 
photometriC_Palette , this color map is ignored. 

The user is responsible for allocating memory to hold the arrays. 

NOTE: If you want to load a color map from a generic display, you 
can use the Generic Display Interface routine CMSR_display_ 
read_color_map. 


DESCRIPTION 

CMSR_image_field_to_f ile_simple transfers an image directly from the speci¬ 
fied field to an image file. 

CMSR_image_£ield_to_file_simple returns non-negative integers on success 
and CMSR IMAGE ERROR if an error is detected. 


SEE ALSO 

CMSR_image_field_to_file 
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CMSRJmage_file_to_array 

Transfers an image from an image file to a front-end array. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
int 

CMSR_image_f i le__to__ar r ay 

(* filename, image array, image info, image number) 

char * filename 

CMS R__gene r i c_p o i n t e r__ t image_array 

CMSR_image__info_t image_info 

int imagenumber 


Fortran Syntax 


INCLUDE '/usr/include/cm/cmtiff-fort.h' 


& 


INTEGER FUNCTION CMSR_IMAGE_FI LEJTO_ARRAY 

( filename, image array, image_info, image number) 


CHARACTER* (*) 
ANY_FE_ARRAY 
INTEGER 
INTEGER 


filename 
image_array 
image info 
imagejiumber 


ARGUMENTS 

filename The file from which the image is to be read. 

image_array The array on the front-end computer to which the image is to be 

written. The image array may be of any data type that provides an 
appropriate number of bits for the depth of the image stored in the 
file. 

In C the CMSR__genericjpointer_t data type accepts a pointer 
to any data type. It is used to make code portable between ANSI 
compilers that accept pointers to void and VAX compilers that 
would require a pointer to char for unspecified data types. You 
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CMSR_image_file_to_array 


may need to cast this variable to the data type you use for your 
array to avoid compiler warnings. 

imagejnfo A CMSR_image_inf o_t data structure that is filled with 

specifications for the image when it is loaded from the file. If you 
do not wish to load this information, you can pass in NULL or zero 
for this field. This argument is then ignored and data describing 
the image is not returned. 

imagenumber The number of the image in the TIFF file that should be displayed. 

TIFF files may contain multiple images. The Image File Interface 
numbers images starting at zero. If the number of images in the 
file is less than the requested number, EOF (-1) is returned. 


DESCRIPTION 

CMSR_image_file_to_array transfers an image from filename to the front-end 
array image_array. 

When reading an image from a file to a front-end array, this routine automatically sets 
the imagejnfo structure to describe the image. 

CMSR_image_f ile_to_array returns non-negative integers on success, EOF (-1) on 
end of file, and cmsr_image_error if an error is detected. 

If there are not enough images in the file to fulfill a read request, EOF is returned. 


ERRORS 

An error is signalled if 

the specified file cannot be opened for reading 
an error occurs while reading scanlines from the file 


SEE ALSO 

CMSR_iniage_file_to_field 

CMSR_image_file_to_display 
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CMSRJmage_file_to_display 


CMSR_image_file_to_display 

Transfers an image directly from a file to the current generic display. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
int 

CMS R_ima ge_f i le__t o__di splay 

(*filename, image info, image number) 

char * filename 

CMSR_image_info__t image_info 
int image number 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

INTEGER FUNCTION CMSRJEMAGEJFILEJTOJDISPLAY 

& ( filename, image Jnfo, imagejiumber) 


CHARACTER* (*) filename 
INTEGER image Jnfo 

INTEGER imagejiumber 


ARGUMENTS 

filename The file from which the image is to be read. 


image info A CMSR__image_inf o__t data structure that is filled with 

specifications for the image when it is loaded from the file. If you 
do not wish to load this information, you can pass in NULL or zero 
for this field. This argument is then ignored and data describing 
the image is not returned. 

imagejiumber The number of the image in the TIFF file that should be displayed. 

TIFF files may contain multiple images. The Image File Interface 
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numbers images starting at zero. If the number of images in the 
file is less than the requested number, EOF (-1) is returned. 


DESCRIPTION 

CMSR_image_file_to_display transfers an image directly from filename to the 
currently selected Generic Display display. The display should be at least as deep as the 
image stored in the file. 

You can read the depth of the image from the image information structure with 
CMSR_image_depth. You can read the information structure from a file before trans¬ 
ferring the image by calling CMSR_image_get_info. 

When reading an image from a file to a Generic Display display, this routine automati¬ 
cally sets the image info structure to describe the image. 

If the image has a color map, that color map is installed on the generic display. If the 
image is a grayscale image, the correct grayscale color map (based on the photometric 
interpretation specified with the file) is installed. 

CMSR_image_f ile_to_display returns non-negative integers on success, EOF (-1) 
on end of file, and CMSR_image_error if an error is detected. 

If there are not enough images in the file to fulfill a read request, EOF is returned. 


ERRORS 

An error is signalled if 

the specified file cannot be opened for reading 
an error occurs while reading scanlines from the file 


SEE ALSO 

CMSR_image_f i 1 e_to_f ie Id 
CMSR_image_file_to_array 
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CMSRJmage_file_to_field 

Transfers an image from a TIFF image file to an image buffer field in CM memory. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
int 

CMSR_image_f i le_to_f ield 

(*filename, destJield, dlen, imageJnfo, imagejmmber, 
x_yaries Jastest_p) 

char * filename; 

CM_f i e 1 d__i d_ t destJield; 

unsigned int dlen; 

CMSR_image_inf o__t image Jnfo; 
int imagejmmber; 

int xvaries Jastest_p; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 


INTEGER FUNCTION CMSRJEMAGE_FILE_TO_FIELD 

& ( filename , destJeld, dlen, image Jnfo, imagejmmber, x_varies Jastestj?) 


CHARACTER* (*) 

INTEGER 

INTEGER 

INTEGER 

INTEGER 

LOGICAL 


filename 
destJield 
djen 

image info 
imagejmmber 
xjyaries Jastestjp 


ARGUMENTS 

filename The file from which the image is to be read. 

dest Jeld The field ID of the field in CM memory to which the image is to 

be written. 
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dlen The length, in bits, of the destination field that is to contain the 

image. 

The field should be at least as deep as the image stored in the file. 
If it is deeper, the field is first zeroed and the image is placed in 
the least significant bits. 

imagejnfo A CMSR_image_info_t data structure that is filled with 

specifications for the image when it is loaded from the file. If you 
do not wish to load this information, you can pass in NULL or zero 
for this field. 

image number The number of the image in the TIFF file that should be displayed. 

TIFF files may contain multiple images. The Image File Interface 
numbers images starting at zero. If the number of images in the 
file is less than the requested number, EOF (-1) is returned. 

x_variesJastestj> A boolean or logical specifying whether the image is stored in the 
field such that the x or y coordinate varies fastest. Normally, 
x_variesJastest_p should be set to true. 

If x_variesJastest_p is true (.TRUE, in Fortran, non-NULL in C, 
non-nil in Lisp), the image data is organized so that the x 
coordinate varies fastest, that is, in column-major order. This is 
the case for Fortran language arrays, and for C arrays that are 
referenced [y][x]. 

\fx_yariesJastest p is false (.FALSE, in Fortran, NULL in C, nil 
in Lisp), the image data is organized so that they coordinate varies 
fastest, that is, in row-major order. This is the case for C arrays 
referenced [x][y]. 

The *Render display routines assume that x varies fastest and map 
axis 0 of the image field to the x dimension of the display. If your 
image arrays are stored so that y varies fastest, x_variesJastest 
should be set to FALSE. 


DESCRIPTION 

CMSR_image_file_to_field transfers an image directly from an image file to the 
specified CM field. The field should be at least as deep as the image stored in the file. If 
the field is deeper than the image data, the field is first zeroed and the image data is 
placed in the least significant bits. 
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You can read the depth of the image from the image information structure with 
CMSR_image_depth. You can read the information structure from a file before trans¬ 
ferring the image by calling CMSR_image_get_info. 

This routine returns non-negative integers on success, EOF (-1) on end of file, and 
CMSR_lMAGE_ERROR if an error is detected. 

If there are not enough images in the file to fulfill a read request, EOF is returned. 


ERRORS 

An error is signalled if 

the specified file cannot be opened for reading 
an error occurs while reading scanlines from the file 


SEE ALSO 

CMSR_image_f i 1 e_to_di splay 
CMSR_image_file_to_array 
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cmdisplay2tiff 

Copies an image from CM framebuffer to a TIFF file. 


SYNTAX 

UNIX Shell-Level Command 


cmdisplay2tiff [-append] [-x offset ] [-y offset ] [-w width] 
[-h height ] [-artist name] [-host name ] 

[-description string] [-software name] 

[-separate] [-nocomp | -lzw] 

[-rowsperstrip number] filename 


ARGUMENTS 


-append 

Adds the current image to the end of the file. 

-x offset 

Starting pixel offset from the left of the screen. Defaults to zero. 

-y offset 

Starting pixel offset from the top of the screen. Defaults to zero. 

-w width 

Width in pixels of the image region to transfer. Defaults to width 
of the screen divided by current x zoom factor. 

-h height 

Height in pixels of the image region to transfer. Defaults to the 
height of the screen divided by current y zoom factor. 

-dpi number 

Specify the number of dots per inch (in both x and y) for the 
image. The default is to omit resolution information from the 
created file. Note that applications are not required to use this 
information even when it is present in a TIFF file. 

-artist name 

Name of the creator of the image. Defaults to user name. 

-host name 

Name of the machine on which the image was created. Defaults 
to name of the local host. 


-description string 

Optional description to be stored with the image. Defaults to 
NULL. 
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-software name Name of the software used to created the image. Defaults to 
cmdisplay2 tiff. 

-separate Stores RGB images in separate planes for each color component. 

The default is to store images contiguously, but separate planes 
may compress more efficiently for some images. 

-nocomp | -lzw 

Type of compression to be used when storing the image, -lzw is 
the default. 

-rowspers trip number 

Number of scanlines in each strip of data in the output file. By 
default this value is set so that the size of each strip is as close to 
8K bytes as possible without going over. 

filename File name in which the image is to be stored. 


DESCRIPTION 

cmdi splay 2 tiff copies an image from a portion of a CM framebuffer to a TIFF file. 
You must be attached to a CM from a sequencer that can access the desired framebuffer. 

If the environment variable CM_DISPLAY is set to the name of a CM framebuffer (as 
described in CMSR_select_display__menu), that display is used as the source of the 
image. 

If CM_DIS PLAY is not set and more than one framebuffer is available, a menu of possi¬ 
ble framebuffers is presented to the user. 

If only one framebuffer is available, it is used as the source of the image. 

NOTE: This command only transfers images from a CM framebuffer generic display. If 
the current generic display is an XI1 display window, you cannot use 

cmdisplay2tiff. 


SEE ALSO 

tiff2cmdisplay 
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tiff2cmdisplay 

Copies an image from a TIFF file to a Generic Display Interface display. 


SYNTAX 

UNIX Shell-Level Command 

tiff2cmdisplay [-x offset ] [-y offset ] [-image number ] 
[-v] [-nozoom] [-nowait] filename 


ARGUMENTS 


-x offset 

The pixel offset from the left edge of the screen. This field only 
applies to CM framebuffers, and defaults to zero. 

-y offset 

The pixel offset from the top edge of the screen. This field only 
applies to CM framebuffers, and defaults to zero. 

-nozoom 

This flag specifies that the framebuffer is not to be panned or 
zoomed. 

-nowait 

When using an X display, tiff2cmdisplay waits after the 
image is displayed until a mouse button is pressed in the window. 
The nowait option specifies that the program is to exit without 
waiting for a button press. 

-image number 

Image to be read from the TIFF file. The first image is number 


zero. 


-v Verbose mode. This flag causes the contents of the image author, 

software, host computer, description, width, height, and depth 
fields to be printed. 


DESCRIPTION 

tiff2cmdisplay reads an image from a TIFF file and displays it on the current 
generic display. The display may be an XI1 server display or a CM framebuffer. 

If the display is a CM framebuffer, the framebuffer is panned so that the offsets speci¬ 
fied with the -x and -y options are at the origin, and is zoomed so that the image 
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nearly fills the screen without being clipped. If you do not explicitly specify offsets, the 
CM framebuffer is panned so that the image is centered. 


SEE ALSO 

cmdisplay2 tiff 
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2.2 Image Information Structure Routines 

This section describes the Image File Interface routines, which set or return fields in the 
image information structure. 

Routines are provided that allocate and deallocate an image information structure, and fill 
an image information structure with the image description from a specified file: 


CMSR_allocate_image_info. 47 

Allocates an image information data structure. 

CMSR_deallocate_jLmage__info . 47 

Deallocates an image information data structure. 

CMSR_JLmage_jjetjLnfo. 49 


Fills image information structure with image description from a specified file. 


Routines that set and read back the image parameters in an Image File Interface image 
information structure are grouped according to whether they set and return image attribute 
parameters, image environment notes, or file format parameters. 


Image Attribute Parameters 

CMSR_image_jset__format . 51 

Sets the file format in which to store images (currently only TIFF). 

CMSR_image_format . 51 

Returns the file format in which to store images (currently only TIFF). 

C^SR_image_set_width / CMSR_image_width. 53 

Sets (returns) image width. 

CMSR — image_set_height / CMSR__image_height . 53 

Sets (returns) image height. 

CMSR_image_depth. 55 

Returns the total number of bits per pixel. 

CMSR_image_set_num_samples . 57 

Sets the number of samples (color components). 

CMSR_image_num_samples . 57 

Returns the number of samples (color components). 

CMSR_image_set_bitsjper__sample. 59 

Sets the number of bits per sample. 
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CMSR_image_bitsjper_sample . 59 

Returns the number of bits per sample. 

CMSR_image_jset_photometric .... 62 

Sets TIFF format photometric interpretation. 

CMSR_image_pho tome trie . 62 

Returns TIFF format photometric interpretation. 

CMSR_image_jset_color_map. 65 

Sets color map arrays. 

CMSR_image__color_map. 65 

Returns color map arrays. 


Image Environment Notes 

CMSR__image_set__artist . 67 

Stores artist’s name. 

CMSR_image__artist . 67 

Returns artist’s name. 

CMSR__image_set_date_time. 69 

Stores date and time. 

CMSR__image__date_time .. 69 

Returns date and time. 

CMSR__image_jset_host_computer. 71 

Stores name or type of host computer. 

CMSR_image__host_computer. 71 

Returns name or type of host computer. 

CMSR_jLmage_jset_description . 73 

Stores text description of the image. 

CMSR_image__description . 73 

Returns text description of the image. 

CMSR__image_set_software. 75 

Stores name of software used to create the image. 

CMSR_JLmage_software. 75 


Returns name of software used to create the image. 
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File Format Parameters 

CMSR_image_set_compression . 77 

Sets the data compression method to be used. 

CMSR_image_compression . 77 

Returns the data compression method to be used. 

CMSR_image_set_planar_config. 79 

Sets the configuration method to be used to store planes of 
color information. 

CMSR_image_planar_config. 79 

Returns the configuration method to be used to store planes of 
color information. 

CMSR_image_set_rows_per_strip. 81 

Sets the number of scanlines stored in each strip of data in the TIFF file. 

CMSR_image_rows_per_strip. 81 


Returns the number of scanlines stored in each strip of data in the TIFF file. 


46 


Version 2.0, November 1991 









Chapter 2. Image File Operations 


CMSR_allocateJmageJnfo 

CMSR_deallocateJmageJnfo 


CMSR_allocateJmageJnfo 

CMSR_deallocateJmageJnfo 

Allocates (deallocates) an image information data structure. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 

CMSR_jLmage__info__t 

CMSR_allocate__image__inf o () 

void 

CMSRjieallocate_image_info ( image info) 
CMSR__image__info__t image Jnfo 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

INTEGER FUNCTION CMSR_ALLOCATE__IMAGE_INFO () 
SUBROUTINE CMSR_JDEALLOCATE__IMAGE__INFO ( imageJnfo) 

INTEGER image Jnfo 


ARGUMENTS 

image Jnfo A CMSR_image__in f o_t data structure containing specifications 

for an image and for the format in which it is to be stored. 


DESCRIPTION 

CMSR_allocate_image__info allocates and returns an image information data 
structure. CMSR_deallocate_image_info deallocates a specified image informa¬ 
tion data structure. 
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CMSR_allocate_image_info 

CMSR_deallocate_image_info 


The Image File Interface routines use the image information structure to interpret data 
when transferring images to or from an image file. When an image is written from the 
CM system to a file, the transfer routines use this information to organize the image 
data in the file and store it with the image data. When a stored image is read back into 
the CM system, these routines automatically load this information into an image infor¬ 
mation structure and use it to configure the display or array to which the image is sent. 

The Image File Interface is described in more detail in Chapter 1. 


SEE ALSO 

CMSR_image_get_info 
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CMSR_image_getJnfo 

Fills image information structure with image description from a specified file. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
int 

CMSR_image_get_info {filename , image Jnfo, image number) ; 

char * filename; 

CMSR_image__inf o__t image info; 
int image_number; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

INTEGER FUNCTION CMSR_IMAGE_GET_INFO 

& {filename, image info, image number) 

CHARACTER* (*) filename; 

INTEGER image Jnfo; 

INTEGER imagejiumber; 


ARGUMENTS 

filename The name of the image file from which to read the image 

information. 


imagejnfo The CMSR__image_inf o_t data structure (created with 

CMSR__allocate_imageji.nf o) that is to be filled. 

imagejiumber The number of the image in filename from which data should be 
read. TIFF files may contain multiple images. The Image File 
Interface numbers images starting at zero. If the number of images 
in the file is less than the requested number, EOF (-1) is returned. 
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DESCRIPTION 

CMSR_image_get_info fills in the image info structure with data describing 
imagenumber image from filename. It does not read in the image data itself. 

This routine returns a non-negative integer if is is successful, EOF (-1) on end of file, 
and CMSR_lMAGE_ERROR if an error is detected. 

If there are not enough images in the file to fulfill a read request, EOF is returned. 


ERRORS 

An error is signalled if the specified file cannot be opened for reading. 


SEE ALSO 

CMSR_allocate_image_info 

CMSR_deallocate_image_info 
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CMSRJmageJormat 


CMSRJmagesetformat 

CMSRJmage_format 

Sets (returns) the file format in which to store images (currently only TIFF). 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR_image__set__format ( image_info , imageJ'ormat) ; 

CMSR_image_in f o__t imageJnfo; 

CMSR_image__f ormat__t image J'ormat; 

CMSR_image_f o rma t_t 

CMSR_image_f orma t (imageJnfo) ; 

CMSR__image__info__t image Jnfo; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR__IMAGE_J3ET_FORMAT (imageJnfo, imageJormat) 

INTEGER image Jnfo 
INTEGER imageJormat 

INTEGER FUNCTION CMSRJEMAGEJFORMAT ( image Jnfo) 

INTEGER image Jnfo 
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CMSR_image_set_format 

CMSR_image_format 


ARGUMENTS 

imageJnfo A CMSR_image_info_t data structure containing specifications 

for an image and for the format in which it is to be stored. 

Image information structures are created with CMSR_allocate_ 
image_info. 

imageJormat The image file format in which the image is to be stored. 

Currently, only CMSR_tiff_file is supported. 


DESCRIPTION 

CMSR_image_set_format sets the file format in the image information structure 
specified by image_info. 

I/O routines in the Image File Interface that specify image Jnfo will store image data in 
the format specified by image Jormat. 

CMSR_image_format returns the image format currently set in the specified image 
information structure. 

Currently, the only valid value for image Jormat is CMSR_tif f_file. 

For more information on the TIFF file format, see Chapter 1. 
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CMSRJmage__set_height 


CMSR_image_set_width / CMSR_image_width 
CMSRJmage_set_height / CMSRJmage_height 

Sets (returns) image width (height). 


SYNTAX 
C Syntax 

#±nclude <cm/cmtiff.h> 
void 

CMSR_image__set_width ( imageinfo , width) ; 
void 

CMSR_image__set__height ( image_info , height) ; 

CMSR__image_JLn f o__t image info; 
int width; 

int height; 


int 

CMSR__image_width (image info) ; 
int 

CMSR_jLmage__height (image_info) ; 
CMSR_jLmage_JLnfo__t imagejnfo; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGE_SET__WIDTH (imagejnfo, width) 

SUBROUTINE CMSR__IMAGE_SET___HEIGHT (imagejnfo, height) 

INTEGER image_info 
INTEGER Width 
INTEGER height 
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CMSR_image_set_width 
CMSR_image_set_height 

INTEGER FUNCTION CMSR_IMAGE_WIDTH (imageJtlfo) 

INTEGER FUNCTION CMSR_IMAGE_HEIGHT ( imagejnfo) 

INTEGER imagejnfo 

ARGUMENTS 

imagejnfo A CMSR_image_info_t data structure (created with 

CMSR_allocate_image_info) containing specifications for 
an image and the format in which it is to be stored. 

width An integer specifying the number of pixels in the image’s x 

(horizontal) dimension. 

height An integer specifying the number of pixels in the image’s y 

(vertical) dimension. 

NOTE: There are no defaults in the image information structure 
for width and height. You must make sure that these fields are set 
correctly before you write an image with CMSR_image_field_ 
to_f ile or CMSR_image_array_to_file. 

CMSR_image_display_to_file determines image informa¬ 
tion defaults from the currently selected generic display. 

DESCRIPTION 

CMSR_image_set_width and CMSR_image_set_height set the image width and 
height, respectively, in the image information structure specified by image jnfo. 

CMSR_image_width and CMSR_image_height return, respectively, the current 
width and height, set in the image information structure specified by imagejnfo. 

I/O routines in the Image File Interface that specify imagejnfo configure the image 
file, or display for image data that is ( width x height). 

SEE ALSO 

CMSR_image_depth 
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CMSR_Jmage_depth 

Returns the number of bits per pixel. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
int 

CMSR_image_dep th ( imageJnfo) 

CMSR_image__inf o__t image Jnfo 

Fortran Syntax 

INCLUDE ' /usr/include/cm/cmtiff-fort.h' 
INTEGER FUNCTION CMSR__IMAGE_DEPTH (image info) 
INTEGER image Jnfo 


ARGUMENTS 

image info A CMSR_image_info__t data structure (created with 

CMSR_allocate__image_info) containing specifications for an 
image and for the format in which it is to be stored. 


DESCRIPTION 

CMSR__image_dep th returns the depth, in bits, for the image defined by image Jnfo. 

The depth of the image is determined by the number of samples per pixel times the 
number of bits per sample. This is the total length of the field or variable needed to hold 
the image. 
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SEE ALSO 

CMSR_image__s e t__width 
CMSR__image__width 
CMSR_image_set_height 
CMSRjLmage__he i gh t 
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CMSRJmage_set_num_samples 

CMSRJmage_num_samples 


CMSR_Jmage_set_num_samples 

CMSR_image_num__samples 

Sets (returns) the number of samples (color components). 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR__image_set_num_samp 1 es (imagejnfo, samples_perjpixel) ; 

CMSR__image_info__t imagejnfo ; 
int samples _per_pixel; 


int 

CMSR_image_num_samples (image info) ; 
CMSR_image__inf o_t imageJnfo ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGEJSET_NUM_SAMPLES 

& (imageJnfo, samplesjperjpixel) 


INTEGER image Jnfo 
INTEGER samples jer jixel 

INTEGER FUNCTION CMSR_IMAGE_NUMJ3 AMPLE S (imagejnfo) 
INTEGER imagejnfo 


ARGUMENTS 

imagejnfo A CMSR_image_info_t data structure (created with 

CMSR_allocate_image_inf o) containing specifications for an 
image and for the format in which it is to be stored. 
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CMSR_image_set_num_samples 

CMSR_image_num_samples 


samples_per_pixel The number of color components of image information that are 
maintained for each pixel in the image. 


DESCRIPTION 

CMSR_image_set_num_samples sets the number of samples per pixel in the 
image info image information structure. 

CMSR_image_num_s ample s returns the number of samples per pixel. 

The number of samples is the number of color components that are maintained per 
pixel in the image to be stored. Currently, the number of samples supported by the 
Image File Interface are 

1 for bilevel, grayscale, or palette images 

3 (red, green, and blue) for RGB true color images 

4 (red, green, blue, and alpha) for RGB plus alpha channel images 

NOTE: When the number of samples per pixel is greater than one, each sample must 
have the same number of bits. 

There is no default in the image information structure for samples_per_pixel. Before 
you write an image with CMSR_image_field_to_file or CMSR_image_array_ 
to_file, make sure that samples_per jpixel is set correctly. 

CMSR_image_display_to_file determines image information defaults from the 
currently selected generic display. 


SEE ALSO 

CMS R__image_s e t_b i t s_jpe r_s amp 1 e 

CMSR_image_bits_j?er_sample 

CMSR_image_depth 
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CMSR_image_set_bits_per_sample 

CMSRJmage_bits_per_sample 


CMSR_image_set_bits_per_sample 

CMSRJmage__bits_per_sample 

Sets (returns) number of bits per sample. 


SYNTAX 
C Syntax 

♦include <cm/cmtiff.h> 
void 

CMSR_image__set_bits_per__sample (imageJnfo, bits_per sample) 

CMSR__image__inf o_t image_info; 
int bits _per_sample; 


int 

CMSR_image_bi t s_j?er_sample ( image info ) ; 
CMSR_image_info_jt image info; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSRJEMAGEJSETJBITS__PERJSAMPLE 

& ( image_info , bits_per_sample) 


INTEGER imageJnfo 
INTEGER bits_per_sample 

INTEGER FUNCTION CMSRJEMAGE_BITS_PERJSAMPLE (imageJnfo) 
INTEGER image Jnfo 
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CMSR_image_set_bits_per_sample 

CMSR_image_bits_per_sample 


ARGUMENTS 

image info A CMSR_image_info_t data structure (created with 

CMSR_allocate_image_inf o) containing specifications for an 
image and for the format in which it is to be stored. 

bits_per_sample For one sample per pixel, the bits per sample may be 1,2,4, or 8. 

For three or four samples per pixel, the bits per sample must be 8. 


DESCRIPTION 

CMSR_image_set_bits_per_sample sets the number of bits per sample in the 
image info image information structure. 

CMSR_image_bits^per_sample returns the number of bits per sample. 

The number of samples is the number of color components that are maintained per 
pixel in the image to be stored. 

The number of bits per sample determines the number of colors that may be repre¬ 
sented in the color map used to display the image. For example, an image with one 
sample per pixel and 1 bit per sample can express only two colors, 0 or 1. A one-sample 
image with 8 bits per sample can reference 256 colors, 0 to 255. 

For the most common classes of images, the following numbers of bits per sample are 
supported: 

Bilevel images must be 1 bit per sample 
Grayscale images can be 4 or 8 bits per sample 
Palette color images can be 1, 2, 4, or 8 bits per sample 
RGB full-color images must be 8 bits per sample 
RGB plus alpha images must be 8 bits per sample 

When the number of samples per pixel is greater than one, each sample must have the 
same number of bits. 

NOTE: There is no default in the image information structure for bits_per_sample. You 
must make sure that this field is set correctly before you write an image with 

CMSR_image_field_to_f ile or CMSR_image_array_to_file. 

CMSR_image_display_to_file determines image information defaults from the 
currently selected generic display. 
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CMSRJmage_set_bits_per_sample 

CMSRJmage_bits_per_sample 


SEE ALSO 

CMSR__image_s e tjmmjs amp 1 e s 
CMSR__image_num__s ample s 
CMSR__image__dep th 
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CMSRJmage_set_photometric 

CMSRJmage_photometric 


CMSRJmage_set_photometric 

CMSRJmage_photometric 

Sets (returns) TIFF format photometric interpretation in an image information structure. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR__image_s e t_pho tome trie (imageJnfo, photometric) ; 

CMSR_image__i n f o_t image Jnfo ; 
int photometric ; 


int 

CMSR__image_jpho tome trie (image info) ; 
CMSR_image_info__t image info; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGEjSET_PHOTOMETRIC (imageJnfo, photometric) 

INTEGER image Jnfo 
INTEGER photometric 

INTEGER FUNCTION CMSR_IMAGE_PHOTOMETRIC (imagejnfo) 

INTEGER imagejnfo 
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CMSR_image_set_photometric 

CMSR_image_photometric 


ARGUMENTS 

image info A CMSR_image_inf o_t data structure containing specifications 

for an image and for the format in which it is to be stored. 

Image information structures are created with CMSR_allocate_ 
image_info. 

photometric Specifies how the image data is to be interpreted by Image File 

Interface. Possible values can be: 

■ PHOTOMETRIC_MINISWHITE 

■ PHOTOMETRICJMINISBLACK 

■ PHOTOMETRIC_PALETTE 

■ PHOTOMETRIC_RGB 

NOTE: There is no default photometric interpretation in the image 
information structure. You must make sure that this field is set 
correctly before you write an image with CMSR_image_f ield_ 
to_file or CMSR_image_array_to_file. 

CMSR_image_display_to_f ile determines image informa¬ 
tion defaults from the currently selected generic display. 


DESCRIPTION 

CMSR_image_set_photometric sets the photometric interpretation of the image 
data. The photometric interpretation specifies how the samples of color information 
stored for each pixel are to be interpreted. To interpret the image data correctly, a 
photometric interpretation field must be supplied. This tells applications whether the 
image is RGB, palette color, or whether the minimum pixel value is black or white. 

CMSR_image_pho tome trie returns the photometric interpretation of the image data. 

The photometric interpretation values are interpreted as follows: 

PHOTOMETRICJMINISWHITE 

The image data is to be mapped so that pixels with a value of 0 are rendered as 
white. 

This photometric interpretation may be used with bilevel or grayscale images. 
In the case of bilevel displays, pixels with a value of 0 are displayed as white 
and pixels with a value of 1 are black. In the case of grayscale images, the pixel 
value is mapped to a range of gray intensities running from white at 0 to black 


Version 2.0, November 1991 


63 



Image File Interface Reference Manual for Paris 


CMSR_image_set_photometric 

CMSR_image_photometric 


at the maximum color map entry. The number of color map entries is deter¬ 
mined by the number of bits per sample. 

PHOTOMETRIC_MINISBLACK 

The image data is to be mapped so that pixels with a value of 0 are rendered as 
black. 

This photometric interpretation may be used with bilevel or grayscale images. 
In the case of bilevel displays, pixels with a value of 0 are displayed as black 
and pixels with a value of 1 are white. In the case of grayscale images, the pixel 
value is mapped to a range of gray intensities running from black at 0 to white 
at the maximum color map entry. The number of color map entries is deter¬ 
mined by the number of bits per sample. 

PHOTOMETRIC_PALETTE 

The image data is to be interpreted as an index into color map. The data must 
have one sample per pixel, and the number of bits per sample can be 1,2, 4, 
or 8. 

The number of entries in the color map is 2 A (bits per sample) entries. For ex¬ 
ample, an 8-bit color map has 256 entries indexed from 0 to 255; a 4-bit map 
has 16 entries indexed from 0 to 15. 

PHOTOMETRIC_RGB 

The image data is to be interpreted as RGB true-color data. The images must 
have three samples per pixel and 8 bits per sample. Each sample expresses a 
color intensity from 0 (off) to 255 (full intensity.) The first sample is used to 
determine the red intensity of the color, the second sample the green intensity, 
and the third sample the blue intensity. 
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CMSRJmage_color_map 


CMSRJmage_set_color_map 

CMSR_image_color_map 

Sets (returns) color map arrays in an image information structure. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR_image__set__co 1 or_map (image_info, red, green, blue) 

CMSR_image_info_t imageJnfo 

float red [ ], green [ ], blue [ ] ; 


void 

CMSR_jLmage_co 1 or_map (imageJnfo, red, green, blue) 

CMSR_image_jLnf o_t image Jnfo 

float red [ ], green [ ], blue [ ] ; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_lMAGEjSET_COLOR__MAP (imageJnfo, red, green, blue) 

INTEGER image Jnfo 

REAL red(), green (), blue() 

SUBROUTINE CMSR_IMAGE_COLOR__MAP (imageJnfo, red, green, blue) 

INTEGER image Jnfo 

REAL red (), green (), blue () 
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CMSR_image_set_color_map 

CMSRJmage_color_map 


ARGUMENTS 

imageinfo A CMSR_image_info_t data structure (created with 

CMSR_allocate_image_inf o) containing specifications for an 
image and for the format in which it is to be stored. 

red, green, blue Arrays of color values specifying the red, green, and blue 
components of a color map. The arrays must each have 
2 A (samples_per_pixel ) elements. 

The user is responsible for allocating memory to hold the arrays. 


DESCRIPTION 

CMSR_image_set_color_map sets the color map arrays in the image information 
structure. 

CMSR_image_color_map returns the color map arrays for palette color images. 

The user is responsible for allocating memory to hold the color map. Each of the three 
elements must point to an area big enough to hold 2 A (bits per sample) floats. 

When photometric interpretation is set to indicate a palette color image, a color map 
must be present. 

SEE ALSO 

CMSR_display_read_color_map 
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CMSR_image_artist 


CMSRJmage_set_artist 

CMSRJmage_artist 

Stores (returns) artist’s name in an image information structure. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR_image__set_artist (image info, * string) ; 

CMSR_image_in f o_t image_info ; 
char * string; 


char * 

CMSR__image_artist (image info) ; 
CMSR_image_info__t imageJnfo; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSRJCMAGEJ3ET_ARTIST (imageJnfo, String) 

INTEGER image Jnfo 

CHARACTER* (*) String 

CHARACTER* (*) FUNCTION CMSR_IMAGE_ARTIST (imageJnfo) 
INTEGER image Jnfo 
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CMSR_image_set_artist 

CMSR_image_artist 


ARGUMENTS 

image info A CMSR_image_info_t data structure (created with 

CMSR_allocate_image_info) containing specifications for an 
image and for the format in which it is to be stored. 

string A character string containing the artist’s name. 

DESCRIPTION 

CMSR_image_set_artist sets the artist field in the image information structure. 
CMSR_image_artist returns the artist field from the image information structure. 
Artist defaults to the user’s login name. 
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CMSRJmage_date_time 


CMSRJmage_set_date_time 

CMSRJmage_date_time 

Stores (returns) date and time in an image information structure. 


SYNTAX 

C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR__image_s e t__da te__t ime ( image info, * string) 

CMSR_image_info__t image_info 
char * string 

char * 

CMSR_image__date_time ( imageJnfo ) 

CMSR_image_inf o__t image info 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR__IMAGE_J3ET__DATE_TIME ( image_info, String) 

INTEGER imagejnfo 

CHARACTER* (*) string 

CHARACTER* (*) CMSR_IMAGE_DATE_TIME ( imagejnfo) 
INTEGER imagejnfo 
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CMSRJmage_set_date_time 

CMSR_image_date_time 


ARGUMENTS 

image info A CMSR_image_info_t data structure containing specifications 

for an image and for the format in which it is to be stored. 

Image information structures are created with CMSR_allocate_ 
image_info. 

string A character string containing the date and time. 

DESCRIPTION 

CMSR_image_set_date_time sets the date and time field in the image information 
structure. 

CMSR_image_date_time returns the date and time field from the image information 
structure. 

Date and time default to current date and time on the system. 
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CMSRJmageJiost_computer 


CMSRJmage_set_host_computer 

CMSR_image_host_computer 

Stores (returns) name or type of host computer in an image information structure. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR__iinage__set__host__computer ( imageinfo , * string) ; 

CMSR_image__info_t imageJnfo; 
char * string; 


char * 

CMSR__image_host_computer ( image info) ; 
CMSR__image__info__t image info; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGE_SET_HOST_COMPUTER ( imageJnfo , string) 

INTEGER imageJnfo 

CHARACTER* ( *) String 

CHARACTER* ( *) CMSR_IMAGE_HOST_COMPUTER ( image Jnfo ) 
INTEGER image_info 


ARGUMENTS 

imagejnfo A CMSR_image < _info_t data structure (created with 

CMSR_allocate_image_inf o) containing specifications for an 
image and for the format in which it is to be stored. 
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CMSR_image_set_host_computer 

CMSR_image_host_computer 


string A character string containing the information you wish to store in 

the imagejnfo structure. 


DESCRIPTION 

CMSR_image_set_host_computer sets the host computer field in the image infor¬ 
mation structure. 

CMSR_image_host_computer returns the host computer field from the image infor¬ 
mation structure. 

Host computer defaults to the name of the local host. 
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CMSR_image_description 


CMSR_image_set__description 

CMSR_image__description 

Stores (returns) text description of the image in an image information structure. 


SYNTAX 

C Syntax 

#include <cm/cmtiff.h> 
void 

CMSRJLmage_set__description ( image_info , *string) ; 

CMSR_JLmage_jLnfo__t image info; 
char * string; 


char * 

CMSR_J.mage_description ( imageJnfo) ; 
CMSR_jLmage__inf o__t image Jnfo; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR__IMAGE__SET_DESCRIPTION (imageJnfo, String) 

INTEGER image Jnfo 

CHARACTER* (*) String 

CHARACTER* (* ) CMSR_IMAGE_DESCRIPTION ( image info) 
INTEGER image Jnfo 


ARGUMENTS 

image Jnfo A CMSR__image__inf o__t data structure (created with 

CMSR__allocate_image_JLnfo) containing specifications for an 
image and for the format in which it is to be stored. 
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CMSR_image_set_description 

CMSRJmage_description 


string A character string containing the information you wish to store in 

the image info structure. 


DESCRIPTION 

CMSR_image_set_description sets the description field in the image information 
structure. 

CMSR_image_description returns a description field from the image information 
structure. 

The description field defaults to NULL. 
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CMSR_image_software 


CMSR_image_set_software 
CMS R_i m ag e_s oftwa re 

Stores (returns) name of software used to create the image in an image information 
structure. 


SYNTAX 

C Syntax 

♦include <cm/cmtiff.h> 
void 

CMSR__image__s e tjs o f twar e (imageJnfo, * string) ; 

CMSR__image__info_t image info ; 
char * string; 

char * 

CMSR_ji.mage_jsof tware (imageJnfo) ; 

CMSR_jLmage__in f o__t image Jnfo ; 

Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGE_SETjSOFTWARE (imageJnfo, string) 

INTEGER image info 

CHARACTER* (*) String 

CHARACTER* (*) CMSRJEMAGE^SOFTWARE ( imageJnfo) 
INTEGER image Jnfo 
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CMSR_image_software 


ARGUMENTS 

imagejnfo A CMSR_image_info_t data structure (created with 

CMSR_allocate_image_inf o) containing specifications for an 
image and for the format in which it is to be stored. 

string A character string containing the information you wish to store in 

the imagejnfo structure. 


DESCRIPTION 

CMSR_image_set_software sets the software field in the image information 
structure. 

CMSR_image_sof tware returns a software field from the image information 
structure. 

The software field defaults to NULL. 
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CMSRJmage_compression 


CMSRJmage_set_compression 

CMSRimagecompression 

Sets (returns) the data compression method to be used. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR_image_set_comp ression ( image Jnfo , compression) 

CMSR__image_inf o_t image Jnfo; 
int compression ; 


int 

CMSR__image__compression ( image info ) ; 
CMSR_image_inf o_t image Jnfo; 


Fortran Syntax 

INCLUDE f /usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGE__SET__COMPRE S SI ON (image info , compression) 

INTEGER image Jnfo 
INTEGER compression 

INTEGER FUNCTION CMSR_IMAGE_COMPRE S SI ON (imagejnfa) 

INTEGER image Jnfo 
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ARGUMENTS 

image info A CMSR_image_info_t data structure containing specifications 

for an image and for the format in which it is to be stored. 

Image information structures are created with CMSR_allocate_ 
image_info. 

compression 

The value may be one of: 

■ COMPRESSION_LZW 

■ COMPRE SSION_NONE 

The default is compression lzw. 


DESCRIPTION 

CMSR_image_set_compression sets the TIFF compression scheme in the specified 
image info structure. 

The default is the general compression strategy lzw . lzw uses the Lempel-Ziv and 
Welch algorithm for data compression. This is a general purpose compression algo¬ 
rithm that works well on any type of image. The algorithm is described in detail in 
Appendix F of the TIFF (Tagged Image File Format) 5.0 specification as published by 
Aldus Corporation and Microsoft Corporation. 

Most other TIFF readers accept the LZW compression strategy. However, if you are 
transferring the image to another graphics environment, check on the compression 
strategies supported by the software you will be using there. If you do not know what 
compression methods are supported, we recommend no compression (NONE). Images 
stored with no compression should be acceptable to nearly all TIFF readers. 

CMSR_image_compression returns the compression scheme of the current image. 
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CMSRJmage_planar_eonfig 


CMSR_image_set_planar_config 

CMSR_image_planar_config 

Sets (returns) the configuration method to be used to store planes of color information. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR__image_set_jplanar_config (image info , configuration) ; 

CMSR_image_in fo_t imagejnfo ; 
int configuration ; 


int 

CMSR_jLmage_jplanar__config ( image info) ; 
CMSR_image_info__t image info ; 


Fortran Syntax 

INCLUDE ' /usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGE__SET_PLANAR__CONFIG 

& (image_info, configuration) 

INTEGER image_info 
INTEGER configuration 

INTEGER FUNCTION CMSR_IMAGE_PLANAR__CONFIG (imagejnfo) 
INTEGER imagejnfo 


ARGUMENTS 

imagejnfo A CMSR_jLmage_info_t data structure containing specifications 

for an image and for the format in which it is to be stored. 
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CMSR_image_planar_config 


Image information structures are created with CMSR_allocate 
image_info. 

configuration The value can be: 

■ PLANARCONFIG_CONTIG 

■ PLANARCONFIG_SEPARATE 
This defaults to PLANARCONFIG CONTIG. 


DESCRIPTION 

CMSR_image_set_planar_config sets the planar configuration of the current 
image. 

CMSR_imagejplanar_conf ig returns the planar configuration of the current image. 

This field is only relevant for images with more than one sample per pixel. It deter¬ 
mines whether the image color components are stored as a contiguous array or as 
separate planes. 

The configuration values are interpreted as follows: 

PLANARCONFIG_CONTIG 

Store the color components in a single contiguous array. For example, an RGB 
image stored contiguously has the samples interleaved: RGBRGBRGB... 

Contiguous arrays must be {samples_perjpixel x width) columns by ( height ) 
rows. The array must be bits_per_sample bits deep. 

PLANARCONFIG_SEPARATE 

Store each color component in a separate plane. An RGB image stored sepa¬ 
rately would have one plane for the red component, another for the green 
component, and a third for the blue component. 

Separate arrays must be ( samples_per_pixel) planes by {width) columns by 
{height) rows. The arrays must be bits_per_sample bits deep. 

Your choice of configuration methods will depend on whether you will be porting the 
image to other software and what compression strategy you wish to use. Many soft¬ 
ware packages will only accept contiguous images because each pixel’s values are 
available in sequence. However, many compression strategies work more efficiently 
when the color samples are stored in separate planes. 
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CMSRJmage_set_rows_per_strip 

CMSRJmage_rows_per_strip 

Sets (returns) the number of scanlines stored in each strip of data in the TIFF file. 


SYNTAX 
C Syntax 

#include <cm/cmtiff.h> 
void 

CMSR_image__set_rows_j?er__strip ( imageJnfo, rows_per_strip) ; 

CMSR_image__inf o__t imagejnfo ; 
int rows_per_strip ; 


int 

CMSR_image__rows_per__strip ( image info) ; 
CMSR__image__inf o__t image Jnfo; 


Fortran Syntax 

INCLUDE '/usr/include/cm/cmtiff-fort.h' 

SUBROUTINE CMSR_IMAGE_SET_ROWS_PERjSTRI P 

& {imageJnfo, rows_perjstrip) 

INTEGER imagejnfo 
INTEGER rows_per_strip 


INTEGER FUNCTION CMSRJEMAGE_ROWS_PER_STRIP (imagejnfo) 
INTEGER imagejnfo 


Version 2.0, November 1991 


81 




Image File Interface Reference Manual for Paris 


CMSR_image_set_rows_per_strip 

CMSR_image_rows_per_strip 


ARGUMENTS 

image info A CMSR_image_inf o_t data structure containing specifications 

for an image and for the format in which it is to be stored. 

Image information structures are created with CMSR_allocate_ 
image_info. 

rows_per_strip The number of rows (scanlines) of pixel data to be stored in each 

strip of data in the TIFF file. 


DESCRIPTION 

CMSR_image_set_rows_per_s trip sets the number of scanlines in each strip of 
data in the TIFF file. 

CMSR_image_rows_j>er_strip returns the number of scanlines in each strip of data 
in the TIFF file. 

This parameter allows you to control the amount of data that will be sent with each read 
from the file. This should be adjusted to allow efficient buffering on your system. If not 
specified, the Image File Interface sets the parameter to result in about 8K of data being 
buffered at a time. 
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Alphabetical Index of Routines 


This index lists the Image File Interface routines alphabetically. 


CMSR_a 

CMSR_allocate_image__inf o, 47 

CMSR_d 

CMSR_deallocate__image_inf o, 47 

CMSRJ 

CMSR__image_ar ray__to_f ile, 15 
CMSR_image_ar ray_to_f ile_s imple, 18 
CMSR_image_artist, 67 
CMSR__image_Jbitsjper_s ample, 59 
CMSR_image_color_map, 65 
CMSR_image__compre s s ion, 77 
CMSR_image_date__time, 69 
CMSR_image_dep th, 55 
CMSR_image_description, 73 
CMSR__image_di splay_to_f i 1 e, 22 
CMSR__image_disp_to_file__simp 1 e, 24 
CMSR_image_field_to_f ile, 26 
CMSR_image_field__to__file_jsimple, 29 
CMSR__image_f i le__to_array, 33 
CMSR^image^f ile__to_jii splay, 35 
CMSR_image_fi 1 e__t o_fie 1 d, 37 
CMSR_image__f o rma t, 51 
CMSR_image_get_info, 49 
CMSR__image__height, 53 
CMSR_image_ho s t_compute r, 71 


CMSR_image_num_samples, 57 
CMSR_image_pho tome trie, 62 
CMSR___image_planar__con£ig, 79 
CMSR_image_rows_per_s trip, 81 
CMSR__image_set_artist, 67 
CMSR_image_set_bits_per_samp 1 e, 59 
CMSR__image_set_color_map, 65 
CMSR__image_set_compression, 77 
CMSR_image_set_date_time, 69 
CMSR_image__set_description, 73 
CMSR_image_set_format, 51 
CMS R_image_s e t_he i ght, 53 
CMSR_image_set_host_computer, 71 
CMSR_image_set_num_samples, 57 
CMSR__image_set_pho tome trie, 62 
CMSR_image__set_planar__config, 79 
CMSR_image_set_rows_per_strip, 81 
CMSR_jLmage_set__software, 75 
CMSR_image__set__width, 53 
CMSR_image__software, 75 
CMSR_image_width, 53 

C 

cmdisplay2tiff, 40 

t 

tiff2cmdisplay, 42 
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Keyword Index of Routines 


This index lists the Image File Interface routines sorted by the key words that appear in their names. 


allocate 

CMSR__allocate_image_inf o, 47 
CMSR__deallocate_image__inf o, 47 

array 

CMSR__image_array_to_f i 1 e, 15 
CMSR__image_array_to_f ile_s imple, 18 
CMSR__image_file_to_array, 33 

artist 

CMSR_image_arti s t, 67 
CMSR__image_se t__ar ti s t, 67 

bits_per_sample 

CMSR__image_bits_jper_s ample, 59 
CMSR__image_s e t_bi ts__pe r_s amp 1 e, 59 

color_map 

CMSR__image__color__map, 65 
CMSR__image_s e t_co 1 o r_map, 65 

compression 

CMSR_image__compre s s ion, 77 
CMSR_image_set_compression, 77 

computer 

CMSR__image_host__computer, 71 
CMSR__image_s e t_ho s t__compu te r, 71 


config 

CMSR__image_planar_config, 79 
CMSR_image_set_j>lanar__conf ig, 79 

date 

CMSR__image_date_time, 69 
CMSR_image_set_date__time, 69 

deallocate 

CMSR_deallocate__image_info, 47 

depth 

CMSR_image__depth, 55 

description 

CMSR_image_description, 73 
CMSR_image__set_description, 73 

display 

cmdisplay2tiff, 40 
CMSR_image_display_to_file, 22 
CMSR_image_disp__to_f ile_simple, 24 
CMSR_image_f i 1 e_t o_display, 35 
tiff2cmdisplay, 42 

field 
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